<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.around &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" >
    <link rel="index" title="Index" href="../../genindex.html" >
    <link rel="search" title="Search" href="../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../index.html" >
    <link rel="up" title="Mathematical functions" href="../routines.math.html" >
    <link rel="next" title="numpy.round_" href="numpy.round_.html" >
    <link rel="prev" title="numpy.arctanh" href="numpy.arctanh.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../index.html">
      <img border=0 alt="NumPy" src="../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../routines.html" >Routines</a></li>
          <li class="active"><a href="../routines.math.html" accesskey="U">Mathematical functions</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy.round_.html" title="numpy.round_"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="numpy.arctanh.html" title="numpy.arctanh"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="numpy.arctanh.html"
                        title="previous chapter">numpy.arctanh</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy.round_.html"
                        title="next chapter">numpy.round_</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-around">
<h1>numpy.around<a class="headerlink" href="#numpy-around" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="numpy.around">
<code class="sig-prename descclassname">numpy.</code><code class="sig-name descname">around</code><span class="sig-paren">(</span><em class="sig-param">a</em>, <em class="sig-param">decimals=0</em>, <em class="sig-param">out=None</em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/numpy/numpy/blob/v1.18.1/numpy/core/fromnumeric.py#L3130-L3224"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#numpy.around" title="Permalink to this definition">¶</a></dt>
<dd><p>Evenly round to the given number of decimals.</p>
<dl class="field-list">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>a</strong><span class="classifier">array_like</span></dt><dd><p>Input data.</p>
</dd>
<dt><strong>decimals</strong><span class="classifier">int, optional</span></dt><dd><p>Number of decimal places to round to (default: 0).  If
decimals is negative, it specifies the number of positions to
the left of the decimal point.</p>
</dd>
<dt><strong>out</strong><span class="classifier">ndarray, optional</span></dt><dd><p>Alternative output array in which to place the result. It must have
the same shape as the expected output, but the type of the output
values will be cast if necessary. See <em class="xref py py-obj">ufuncs-output-type</em> for more
details.</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl>
<dt><strong>rounded_array</strong><span class="classifier">ndarray</span></dt><dd><p>An array of the same type as <em class="xref py py-obj">a</em>, containing the rounded values.
Unless <em class="xref py py-obj">out</em> was specified, a new array is created.  A reference to
the result is returned.</p>
<p>The real and imaginary parts of complex numbers are rounded
separately.  The result of rounding a float is a float.</p>
</dd>
</dl>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference internal" href="numpy.ndarray.round.html#numpy.ndarray.round" title="numpy.ndarray.round"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ndarray.round</span></code></a></dt><dd><p>equivalent method</p>
</dd>
</dl>
<p><a class="reference internal" href="numpy.ceil.html#numpy.ceil" title="numpy.ceil"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ceil</span></code></a>, <a class="reference internal" href="numpy.fix.html#numpy.fix" title="numpy.fix"><code class="xref py py-obj docutils literal notranslate"><span class="pre">fix</span></code></a>, <a class="reference internal" href="numpy.floor.html#numpy.floor" title="numpy.floor"><code class="xref py py-obj docutils literal notranslate"><span class="pre">floor</span></code></a>, <a class="reference internal" href="numpy.rint.html#numpy.rint" title="numpy.rint"><code class="xref py py-obj docutils literal notranslate"><span class="pre">rint</span></code></a>, <a class="reference internal" href="numpy.trunc.html#numpy.trunc" title="numpy.trunc"><code class="xref py py-obj docutils literal notranslate"><span class="pre">trunc</span></code></a></p>
</div>
<p class="rubric">Notes</p>
<p>For values exactly halfway between rounded decimal values, NumPy
rounds to the nearest even value. Thus 1.5 and 2.5 round to 2.0,
-0.5 and 0.5 round to 0.0, etc.</p>
<p><code class="docutils literal notranslate"><span class="pre">np.around</span></code> uses a fast but sometimes inexact algorithm to round
floating-point datatypes. For positive <em class="xref py py-obj">decimals</em> it is equivalent to
<code class="docutils literal notranslate"><span class="pre">np.true_divide(np.rint(a</span> <span class="pre">*</span> <span class="pre">10**decimals),</span> <span class="pre">10**decimals)</span></code>, which has
error due to the inexact representation of decimal fractions in the IEEE
floating point standard <a class="reference internal" href="#r907366b089c1-1" id="id1">[1]</a> and errors introduced when scaling by powers
of ten. For instance, note the extra “1” in the following:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="mf">56294995342131.5</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
<span class="go">56294995342131.51</span>
</pre></div>
</div>
<p>If your goal is to print such values with a fixed number of decimals, it is
preferable to use numpy’s float printing routines to limit the number of
printed decimals:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">format_float_positional</span><span class="p">(</span><span class="mf">56294995342131.5</span><span class="p">,</span> <span class="n">precision</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="go">&#39;56294995342131.5&#39;</span>
</pre></div>
</div>
<p>The float printing routines use an accurate but much more computationally
demanding algorithm to compute the number of digits after the decimal
point.</p>
<p>Alternatively, Python’s builtin <a class="reference external" href="https://docs.python.org/dev/library/functions.html#round" title="(in Python v3.9)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">round</span></code></a> function uses a more accurate
but slower algorithm for 64-bit floating point values:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">round</span><span class="p">(</span><span class="mf">56294995342131.5</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
<span class="go">56294995342131.5</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="mf">16.055</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="nb">round</span><span class="p">(</span><span class="mf">16.055</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>  <span class="c1"># equals 16.0549999999999997</span>
<span class="go">(16.06, 16.05)</span>
</pre></div>
</div>
<p class="rubric">References</p>
<dl class="citation">
<dt class="label" id="r907366b089c1-1"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
<dd><p>“Lecture Notes on the Status of IEEE 754”, William Kahan,
<a class="reference external" href="https://people.eecs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF">https://people.eecs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF</a></p>
</dd>
<dt class="label" id="r907366b089c1-2"><span class="brackets">2</span></dt>
<dd><p>“How Futile are Mindless Assessments of
Roundoff in Floating-Point Computation?”, William Kahan,
<a class="reference external" href="https://people.eecs.berkeley.edu/~wkahan/Mindless.pdf">https://people.eecs.berkeley.edu/~wkahan/Mindless.pdf</a></p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">around</span><span class="p">([</span><span class="mf">0.37</span><span class="p">,</span> <span class="mf">1.64</span><span class="p">])</span>
<span class="go">array([0.,  2.])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">around</span><span class="p">([</span><span class="mf">0.37</span><span class="p">,</span> <span class="mf">1.64</span><span class="p">],</span> <span class="n">decimals</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="go">array([0.4,  1.6])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">around</span><span class="p">([</span><span class="o">.</span><span class="mi">5</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">,</span> <span class="mf">2.5</span><span class="p">,</span> <span class="mf">3.5</span><span class="p">,</span> <span class="mf">4.5</span><span class="p">])</span> <span class="c1"># rounds to nearest even value</span>
<span class="go">array([0.,  2.,  2.,  4.,  4.])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">around</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">11</span><span class="p">],</span> <span class="n">decimals</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> <span class="c1"># ndarray of ints is returned</span>
<span class="go">array([ 1,  2,  3, 11])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">around</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">11</span><span class="p">],</span> <span class="n">decimals</span><span class="o">=-</span><span class="mi">1</span><span class="p">)</span>
<span class="go">array([ 0,  0,  0, 10])</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>